1. 왜 마크다운부터인가

AI에게 코드를 짜달라고 부탁하면 결국 두 가지가 오갑니다. 내가 보낸 글과 AI가 돌려준 글. 그 둘 다 마크다운입니다. Claude도, ChatGPT도, Cursor도, GitHub의 README도, Notion 붙여넣기도 마찬가지입니다.

문제는 마크다운 문법을 모르는 채로 AI를 쓰다 보면 자꾸 이상한 자리에서 막힌다는 점입니다. AI가 친절하게 정리해 준 답변을 코드 에디터에 붙였더니 표가 깨지거나, 코드 블록 안에 코드가 또 들어가서 레이아웃이 망가지거나, 시키지도 않은 별표가 잔뜩 붙어 나오는 식입니다. 마크다운을 한 번이라도 정리해 두면 이런 문제가 거의 사라집니다.

이 책은 마크다운의 모든 문법을 다 다루지 않습니다. AI와 일할 때 자주 마주치는 부분만 골라서 다룹니다. 30분이면 충분합니다.

실습은 https://just.weniv.co.kr/ 에서 바로 해보실 수 있습니다. 별도의 설치 없이 브라우저 한 칸에 마크다운을 쓰면 옆 칸에 결과물이 나옵니다. 이 책에 나오는 모든 예제를 거기서 그대로 따라 쳐 보시기를 권합니다.

2. 줄바꿈과 문단

마크다운을 처음 쓰는 사람이 가장 먼저 당황하는 부분입니다. 그냥 엔터 한 번을 치면 줄이 안 바뀐 것처럼 보입니다. 일부 에디터에서는 줄이 바뀌기도 하지만 대부분은 줄이 안 바뀌고 그냥 붙어서 나옵니다.

첫 줄을 썼습니다.
두 번째 줄을 썼습니다.

표시 결과는 아래와 같습니다. 줄이 안 바뀌고 붙어서 나옵니다.

첫 줄을 썼습니다. 두 번째 줄을 썼습니다.

규칙은 두 가지입니다.

• 새 문단을 만들고 싶다 → 빈 줄을 한 줄 넣는다
• 줄만 바꾸고 싶다 → 줄 끝에 공백 두 칸을 넣고 엔터

첫 번째 문단입니다.

빈 줄을 사이에 두면 새 문단이 됩니다.

줄 끝에 공백 두 칸을 두면  
강제로 줄바꿈만 됩니다.

3. 헤딩

3.1. 기본 문법

#을 붙이면 제목이 됩니다. 개수가 곧 깊이입니다. 마크다운 문법은 6단계까지 있지만, 보통 Notion이나 GitHub 등에서는 3단계까지만 쓰는 편입니다. Notion은 4단계 이상을 지원하지 않습니다.

# 1단계 (제일 큰 제목, 보통 문서 제목 하나만)
## 2단계
### 3단계
#### 4단계

3.2. 실전에서 자주 쓰는 패턴

문서를 작성할 때는 보통 #은 문서 제목 하나, ##부터가 본문 섹션입니다. AI가 작성한 답변을 그대로 GitHub 이슈에 붙일 때 #이 두 개씩 붙어 있으면 오히려 섹션 제목이 더 잘 어울립니다.

3.3. AI에게 헤딩으로 지시 분리하기

프롬프트를 길게 쓸 때 ##으로 섹션을 나눠 주면 AI가 훨씬 안정적으로 답합니다.

## 역할
초보자에게 친절한 글쓰기 선생님

## 작업
아래 글에서 어색한 문장을 골라 자연스럽게 고쳐줘.

## 글
오늘 날씨가 너무 좋아서 산책을 갔다왔는데 기분이 좋아진것 같다.

## 조건
- 원래 분위기는 유지
- 한 문장씩 비교해서 보여줘

평문으로 "역할은 글쓰기 선생님이고, 작업은 문장 다듬기고, 글은 이거야..."처럼 줄줄이 쓰는 것보다 위처럼 헤딩으로 나누는 편이 결과가 좋습니다. 항목이 분리돼 있으면 AI가 각 부분을 따로따로 정확히 인식합니다.

4. 강조

**굵게**: 별표 두 개로 감싸면 굵은 글씨
*기울임*: 별표 한 개로 감싸면 기울임
~~취소선~~: 물결표 두 개
`인라인 코드`: 백틱 한 개

표시 결과:

• 굵게
• 기울임
• 취소선
• 인라인 코드

실전에서 가장 많이 쓰는 건 굵게와 인라인 코드입니다. 변수명·함수명·파일명·명령어 같은 것을 본문에 끼워 넣을 때는 항상 백틱으로 감싸는 게 좋습니다. Ctrl + C처럼 말입니다.

5. 리스트

5.1. 순서 없는 리스트

- 사과
- 바나나
- 포도
  - 청포도
  - 적포도

들여쓰기는 보통 공백 2칸 또는 4칸입니다. 한 문서 안에서 일관되기만 하면 둘 다 됩니다. 탭과 공백을 섞으면 깨질 때가 있으니 한 가지로 통일하세요.

5.2. 순서 있는 리스트

1. 저장소를 클론한다
2. 의존성을 설치한다
3. 환경변수를 설정한다

재미있는 사실 — 숫자는 아무 숫자나 써도 결과가 자동으로 1, 2, 3으로 매겨집니다.

1. 첫 번째
1. 두 번째
1. 세 번째

이렇게 써도 표시는 1, 2, 3입니다. 중간에 항목을 추가하거나 빼도 번호를 다시 매길 필요가 없으니 편합니다.

5.3. 체크리스트

- [ ] 아직 안 한 일
- [x] 끝낸 일

표시 결과:

• 아직 안 한 일
• 끝낸 일

AI에게 단계별 작업 지시를 줄 때 매우 자주 씁니다. AI에게 "아래 체크리스트 항목을 하나씩 처리하면서 끝내면 [x]로 바꿔서 보여줘"라고 시키는 패턴은 거의 표준입니다.

## 작업 목록
- [ ] 로그인 폼 컴포넌트 작성
- [ ] 유효성 검사 추가
- [ ] 에러 메시지 표시
- [ ] 단위 테스트

6. 코드 블록

6.1. 인라인 코드 vs 코드 블록

한 줄짜리 코드나 변수명은 백틱 하나, 여러 줄은 백틱 세 개입니다. 이 블록은 Claude에서는 백틱 부분을 검은색으로 칠해 줍니다. 별도의 영역으로 분리하는 효과가 있습니다.

아래와 같은 메일 초안을 수정해 작성하고 싶어. 더욱 정중하게.

```text
안녕하세요. 저는 위니북스에서 일하는 김바이브라고 합니다. 이번에 마크다운 책을 새로 내게 되었는데, 혹시 홍보에 도움을 받을 수 있을까 해서 연락드렸습니다.
```

코드를 짜시는 분들은 아래와 같이 자주 사용합니다.

인라인은 `console.log("hi")` 이렇게.

여러 줄은 아래와 같이.

```javascript
function greet(name) {
  console.log(`Hello, ${name}`);
}
```

6.2. 언어 표시는 거의 필수

```javascript 처럼 백틱 뒤에 언어 이름을 적으면 색깔이 입혀지고, AI가 그 코드를 더 정확히 분류합니다. 자주 쓰는 키워드:

7. 링크와 이미지

7.1. 기본 링크

[보이는 텍스트](https://example.com)
[위니북스](https://wenivooks.com/)

7.2. 이미지

![대체 텍스트](이미지 경로)
![위니북스](https://weniv.co.kr/images/OG/service/wenivooks.png)

링크 앞에 느낌표 하나가 있으면 이미지입니다. 차이는 그것뿐입니다.

7.3. 자동 링크

URL 앞뒤에 < >를 붙이거나, 그냥 URL을 적으면 자동으로 링크가 됩니다.

<https://example.com>
https://example.com

8. 표

| 도구 | 용도 | 가격 |
|------|------|------|
| Claude | 대화/코딩 | 유료/무료 |
| Cursor | IDE | 유료 |
| ChatGPT | 대화 | 유료/무료 |

표시 결과:

세로 막대 |로 칸을 나누고, 두 번째 줄의 ---이 헤더와 본문을 가르는 신호입니다. ---이 없으면 표로 인식되지 않습니다. 칸의 너비를 일일이 맞출 필요는 없습니다. 다음처럼 공백을 안 넣어도 결과는 똑같습니다. 다만 사람이 읽을 때는 정렬해두는 편이 친절합니다. AI에게 "이 데이터를 마크다운 표로 정리해줘"라고 하면 자동으로 보기 좋게 정렬해 줍니다.

8.1. 정렬

| --왼 쪽-- | --가 운 데-- | --오 른 쪽-- |
|:-----|:------:|------:|
| L    | C      | R     |
| 사과 | 바나나 | 포도  |

:의 위치로 정렬을 정합니다. 왼쪽에 붙이면 좌측 정렬, 양쪽에 붙이면 가운데, 오른쪽에 붙이면 우측 정렬입니다. 제목에 --왼 쪽--처럼 표시해 둔 이유는 실습을 할 때 좀 더 극적으로 정렬이 바뀌는 걸 보여주기 위해서입니다. 실제로는 제목에 저렇게 표시하지 않습니다.

9. 인용

> 한 줄 인용
> 두 번째 줄
>
> 빈 줄로 구분된 두 번째 문단

아래와 같이 표시 됩니다.

한 줄 인용 두 번째 줄

빈 줄로 구분된 두 번째 문단

AI 응답을 인용하거나, 본문 중에 출처가 있는 문장을 따올 때 자주 씁니다. GitHub PR에서 다른 사람의 코멘트를 인용 답변할 때도 자동으로 >이 붙습니다.

10. 이스케이프와 수평선

10.1. 이스케이프

마크다운에서 특별한 의미를 가진 문자(*, _, #, `, [, ] 등)를 그대로 보여주고 싶을 때는 앞에 백슬래시 \를 붙입니다.

\*별표를 평문으로 보여주기\*
\# 이건 헤딩이 아니라 그냥 샵 기호
가격은 100\*2 = 200원입니다

자주 쓸 일은 많지 않습니다. 다만 한 번 막히면 답이 안 나오는 종류의 문제라 알아두면 든든합니다.

10.2. 수평선

빈 줄 사이에 ---을 세 개 이상 쓰면 가로줄이 생깁니다. Notion에서는 ---을 치면 자동으로 수평선이 생기고 발표자료에서도 사용할 수 있으므로 자주 쓰는 편입니다.

첫 번째 주제에 대한 이야기를 마쳤습니다.

---

이제 두 번째 주제로 넘어갑니다.

AI가 답변에서 화제를 전환할 때 자주 넣어 줍니다. 길이를 4개 이상(-----)으로 늘려도 결과는 같습니다.

11. HTML

대부분의 마크다운 처리기는 HTML을 그대로 통과시킵니다. 마크다운으로 표현이 어려울 때는 HTML을 섞어도 됩니다. 이게 의외로 자주 필요합니다.

11.1. 접었다 펴기 (<details>)

<details>
<summary>접었다 펴는 영역</summary>

여기는 펼쳤을 때 보이는 내용입니다.

</details>

표시 결과는 아래와 같습니다.

접었다 펴는 영역

여기는 펼쳤을 때 보이는 내용입니다.

GitHub 이슈에서 긴 로그를 접어둘 때, README에서 자주 묻는 질문(FAQ)을 정리할 때 자주 씁니다.

11.2. 주석 — 보이지 않게 메모 남기기

<!-- --> 안에 쓴 글은 렌더링 결과에 나타나지 않습니다. 작성자만 보는 메모를 남길 때 씁니다.

<!-- TODO: 이 부분은 다음 주에 다시 정리 -->
<!-- 이 표는 분기마다 업데이트 필요 -->

본문 내용은 이렇게 적습니다.

AI에게 프롬프트를 줄 때 "이 메모는 무시하고 본문만 처리해줘"라는 식으로 표시하기도 하고, 협업 문서에 "여기는 다음에 보강 예정" 같은 작업 메모를 남길 때 유용합니다.

11.3. 유튜브 영상 임베드

마크다운에는 영상 삽입 문법이 없습니다. 유튜브 같은 영상은 HTML <iframe>을 그대로 씁니다.

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  frameborder="0"
  allowfullscreen></iframe>

embed/ 뒤의 영상 ID(dQw4w9WgXcQ 자리)만 바꾸면 됩니다. 영상 ID는 유튜브 주소(youtube.com/watch?v=...)에서 v= 뒤의 값입니다. 이 태그는 호환이 안되는 경우도 있습니다.

보여지는 화면은 아래와 같습니다.

12. 머메이드

GitHub, Notion, 그 외 대부분의 마크다운 환경에서 코드 블록 언어를 mermaid로 지정하면 자동으로 다이어그램으로 렌더링합니다.

```mermaid
flowchart LR
    A[프롬프트] --> B[AI]
    B --> C[응답]
```

복잡한 시퀀스 다이어그램, 클래스 다이어그램, 간트 차트도 됩니다. AI에게 "이 시스템의 흐름을 머메이드로 그려줘"라고 하면 다이어그램까지 한 번에 만들어 줍니다.